---
title: Keystatic & Astro
description: Keystatic을 CMS로 사용하여 Astro 프로젝트에 콘텐츠 추가
type: cms
service: Keystatic
i18nReady: true
---

import { FileTree } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

[Keystatic](https://keystatic.com/)은 콘텐츠를 구성하고 GitHub와 동기화할 수 있는 오픈 소스 헤드리스 콘텐츠 관리 시스템입니다.

:::tip
**새 Astro + Keystatic 프로젝트를 처음부터 시작하는 경우** [Keystatic CLI](https://keystatic.com/docs/quick-start#keystatic-cli)를 사용하여 몇 초 만에 새 프로젝트를 생성할 수 있습니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm create @keystatic@latest
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm create @keystatic@latest
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn create @keystatic
  ```
  </Fragment>
</PackageManagerTabs>

Astro 템플릿을 선택하면 [배포](#keystatic--astro-배포)할 준비가 됩니다!
:::

## 전제 조건

- [서버 측 렌더링 (SSR) 및 `output: 'hybrid'` 또는 `output: 'server'`가 구성된](/ko/guides/server-side-rendering/) 기존 Astro 프로젝트.

:::note
Keystatic의 데이터를 GitHub와 동기화하려면 이 프로젝트의 저장소에 **`write` 권한이 있는 GitHub 계정**도 필요합니다.
:::

## 종속성 설치

패키지 관리자의 `astro add` 명령을 사용하여 Astro 프로젝트에 Markdoc (콘텐츠 항목용) 및 React (Keystatic 관리 UI 대시보드용) 통합을 모두 추가하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro add react markdoc
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro add react markdoc
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro add react markdoc
  ```
  </Fragment>
</PackageManagerTabs>

또한 두 개의 Keystatic 패키지가 필요합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @keystatic/core @keystatic/astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @keystatic/core @keystatic/astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @keystatic/core @keystatic/astro
  ```
  </Fragment>
</PackageManagerTabs>

## Astro 통합 추가

Astro 구성 파일에 `@keystatic/astro` Astro 통합을 추가하세요.

```js ins={6} ins=", keystatic()"
// astro.config.mjs
import { defineConfig } from 'astro/config';

import react from '@astrojs/react';
import markdoc from '@astrojs/markdoc';
import keystatic from '@keystatic/astro';

// https://astro.build/config
export default defineConfig({
  integrations: [react(), markdoc(), keystatic()],
  output: 'hybrid',
});
```

## Keystatic 구성 파일 생성

콘텐츠 스키마를 정의하려면 Keystatic 구성 파일이 필요합니다. 또한 이 파일을 사용하면 프로젝트를 특정 GitHub 저장소에 연결할 수 있습니다 (원하는 경우).

프로젝트 루트에 `keystatic.config.ts` 라는 파일을 만들고 다음 코드를 추가하여 저장소 타입 (`local`) 및 단일 콘텐츠 컬렉션 (`posts`)을 모두 정의합니다.

```ts {8-25}
// keystatic.config.ts
import { config, fields, collection } from '@keystatic/core';

export default config({
  storage: {
    kind: 'local',
  },

  collections: {
    posts: collection({
      label: 'Posts',
      slugField: 'title',
      path: 'src/content/posts/*',
      format: { contentField: 'content' },
      schema: {
        title: fields.slug({ name: { label: 'Title' } }),
        content: fields.document({
          label: 'Content',
          formatting: true,
          dividers: true,
          links: true,
          images: true,
        }),
      },
    }),
  },
});
```

:::note[이미 콘텐츠 컬렉션을 사용 중이신가요?]
Astro 프로젝트에서 이미 [콘텐츠 컬렉션](/ko/guides/content-collections/#컬렉션-정의)을 사용하고 있는 경우 기존 스키마에 정의된 컬렉션과 정확히 일치하도록 위 스키마를 업데이트하세요.
:::

Keystatic은 이제 스키마를 기반으로 콘텐츠를 관리하도록 구성되었습니다.

## Keystatic을 로컬에서 실행

Keystatic 관리 UI 대시보드를 시작하려면 Astro의 개발 서버를 시작하세요.

    ```bash
    npm run dev
    ```

실행 중인 Keystatic 관리 UI를 확인하려면 브라우저에서 `http://127.0.0.1:4321/keystatic`을 방문하세요.

## 새 게시물 만들기

1.  Keystatic 관리 UI 대시보드에서 "“Posts”" 컬렉션을 클릭합니다.

2.  버튼을 이용하여 새 게시물을 작성하세요. "My First Post"라는 제목과 내용을 추가한 후 게시물을 저장하세요.

3.  이제 이 게시물이 "Posts" 컬렉션에 표시됩니다. 이 대시보드 페이지에서 개별 게시물을 보고 편집할 수 있습니다.

4.  Astro 프로젝트 파일을 보기 위해 돌아갑니다. 이제 이 새 게시물에 대한 `src/content/posts` 디렉터리에서 새로운 `.mdoc` 파일을 찾을 수 있습니다.

        <FileTree title="Project Structure">
        - src/
          - content/
            - posts/
              - **my-first-post.mdoc**
        </FileTree>

5.  코드 편집기에서 해당 파일로 이동하여 입력한 Markdown 콘텐츠를 볼 수 있는지 확인합니다. 예를 들어:

        ```markdown
        ---
        title: My First Post
        ---

        This is my very first post. I am **super** excited!
        ```

## Keystatic 콘텐츠 렌더링

Astro 프로젝트와 마찬가지로 Astro의 콘텐츠 컬렉션 API를 사용하여 [게시물 및 컬렉션을 쿼리하고 표시](/ko/guides/content-collections/#컬렉션-쿼리)하세요.

### 컬렉션 목록 표시하기

다음 예시에서는 개별 게시물 페이지에 대한 링크와 함께 각 게시물 제목 목록을 표시합니다.

```tsx {4}
---
import { getCollection } from 'astro:content'

const posts = await getCollection('posts')
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
    </li>
  ))}
</ul>
```

### 단일 항목 표시

개별 게시물의 콘텐츠를 표시하려면 `<Content />` 컴포넌트를 가져와 사용하여 [콘텐츠를 HTML로 렌더링](/ko/guides/content-collections/#콘텐츠를-html로-렌더링)할 수 있습니다.

```tsx {4-5}
---
import { getEntry } from 'astro:content'

const post = await getEntry('posts', 'my-first-post')
const { Content } = await post.render()
---

<main>
  <h1>{post.data.title}</h1>
  <Content />
</main>

```

쿼리, 필터링, 컬렉션 콘텐츠 표시 등에 대한 자세한 내용은 전체 콘텐츠 [컬렉션 문서](/ko/guides/content-collections/)를 참조하세요.

## Keystatic + Astro 배포

웹사이트를 배포하려면 [배포 가이드](/ko/guides/deploy/)를 방문하여 선호하는 호스팅 제공업체의 지침을 따르세요.

또한 프로젝트의 배포된 인스턴스에서 콘텐츠를 관리할 수 있도록 [Keystatic을 GitHub에 연결](https://keystatic.com/docs/connect-to-github)하는 것이 좋습니다.

## 공식 자료

- [Keystatic 공식 가이드](https://keystatic.com/docs/installation-astro) 확인하기
- [Keystatic 시작 템플릿](https://github.com/Thinkmill/keystatic/tree/main/templates/astro)
